<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Line coverage
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot090.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot083.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot092.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc213">15.8</A>&nbsp;&nbsp;Line coverage</H2><UL>
<LI><A HREF="umsroot091.html#toc124">Compilation</A>
<LI><A HREF="umsroot091.html#toc125">Results</A>
</UL>

<A NAME="@default882"></A>
<A NAME="@default883"></A>
<A NAME="@default884"></A>
The line coverage library provides a means to ascertain exactly how
many times individual clauses are called during the evaluation of a
query.<BR>
<BR>
<A NAME="@default885"></A>
The library works by placing <EM>coverage counters</EM> at strategic
points throughout the code being analysed. These counters are
incremented each time the evaluation of a query passes them. There
are three locations in which coverage counters can be inserted.
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
At the beginning of a code block.
<LI CLASS="li-enumerate">Between predicate calls within a code block.
<LI CLASS="li-enumerate">At the end of a code block.
</OL>
A code block is defined to be a conjunction of predicate calls. ie. a
sequence of goals separated by commas.<BR>
<BR>
The counter values do not only show whether all code points were 
reached but also whether subgoals failed or aborted (in which case 
the counter before a subgoal will have a higher value than the 
counter after it).<BR>
<BR>
<A NAME="toc124"></A>
<H3 CLASS="subsection"><A NAME="htoc214">15.8.1</A>&nbsp;&nbsp;Compilation</H3>
<A NAME="@default886"></A>
<A NAME="@default887"></A>
In order to add the coverage counters to code, it must be compiled with
the <A HREF="../bips/lib/coverage/ccompile-1.html"><B>ccompile/1</B></A><A NAME="@default888"></A>
predicate which can be found in the 
<A HREF="../bips/lib/coverage/index.html"><B>coverage</B></A><A NAME="@default889"></A> library.<BR>
<BR>
The <TT>ccompile/1</TT> predicate (note the initial `c' stands for
coverage) can be used in place of the normal <TT>compile/1</TT>
predicate to compile a file with coverage counters.<BR>
<BR>
The following shows the results of compiling the <B>n-queens</B> example:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- coverage:ccompile(queen).
queen.ecl  compiled traceable 6016 bytes in 0.01 seconds
coverage: inserted 20 coverage counters into module queen 

Yes (0.14s cpu)
</PRE></BLOCKQUOTE>
Once compiled, predicates can be called as usual and will (by default)
have no visible side effects. Internally however, the counters will
be incremented as the execution progresses. The following demonstrates
this for a single solution to the <TT>queen</TT> predicate:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- queen:queen([1,2,3,4,5,6,7,8,9], Out).
</PRE></BLOCKQUOTE>
The counter results are retrieved as demonstrated in the subsequent section.
The two argument predicate <TT>ccompile/2</TT> <A NAME="@default890"></A>
<A NAME="@default891"></A> can take a list of <TT>name:value</TT> pairs
which can be used to control the exact manner in which coverage
counters are inserted. The documentation for the 
<A HREF="../bips/lib/coverage/ccompile-2.html"><B>ccompile/2</B></A><A NAME="@default892"></A> predicate
provides for a full list of the available flags.<BR>
<BR>
<A NAME="toc125"></A>
<H3 CLASS="subsection"><A NAME="htoc215">15.8.2</A>&nbsp;&nbsp;Results</H3>

<A NAME="@default893"></A> <A NAME="@default894"></A> To generate an HTML file
containing the coverage counter results, the 
<A HREF="../bips/lib/coverage/result-1.html"><B>result/1</B></A><A NAME="@default895"></A> predicate is used:
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- coverage:result(queen).
Writing /examples/coverage/queen.html
index.pl   compiled traceable 335304 bytes in 0.17 seconds

Yes (0.18s cpu)
</PRE></BLOCKQUOTE>
This creates the result file <TT>coverage/queens.html</TT> which
can be viewed using any browser. It contains a pretty-printed form of
the source, annotated with the values of the code coverage counters as
described above. As a side effect, the coverage counters will be reset.<BR>
<BR>
<HR>
<A HREF="umsroot090.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot083.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot092.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
